Skip to content

docs: fix OAuth2 SSO setup and sample project guidance - #5751

Merged
ulischulte merged 4 commits into
codecentric:masterfrom
ozkanpakdil:docs/1195-oauth2-sample-guidance
Nov 20, 2026
Merged

ulischulte merged 4 commits into
codecentric:masterfrom
ozkanpakdil:docs/1195-oauth2-sample-guidance

Conversation

@ozkanpakdil

@ozkanpakdil ozkanpakdil commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

The documented OAuth2 configuration pointed oauth2Login at Spring Boot Admin's own /login page. Because httpBasic() is enabled as well, Spring Security selects the HTTP-Basic entry point, so unauthenticated browser requests get a 401 challenge instead of a redirect to the identity provider, and /login keeps showing the local username/password form with no link to the provider.

Verified by starting an Admin Server with an OIDC registration and issuing requests: GET / returned 401 and /login served the local form, while the corrected wiring returns a 302 to
/oauth2/authorization/{registrationId} and still authenticates a client request carrying preemptive HTTP Basic credentials.

Also redirect the OAuth2 sample reference away from the stale third-party joshiste/spring-boot-admin-samples repository (last updated in 2019) and clarify that new example projects belong in spring-boot-admin-runtime-playground.

Refs #1195

The documented OAuth2 configuration pointed `oauth2Login` at Spring Boot
Admin's own `/login` page. Because `httpBasic()` is enabled as well,
Spring Security selects the HTTP-Basic entry point, so unauthenticated
browser requests get a 401 challenge instead of a redirect to the
identity provider, and `/login` keeps showing the local
username/password form with no link to the provider.

Verified by starting an Admin Server with an OIDC registration and
issuing requests: `GET /` returned 401 and `/login` served the local
form, while the corrected wiring returns a 302 to
`/oauth2/authorization/{registrationId}` and still authenticates a
client request carrying preemptive HTTP Basic credentials.

Also redirect the OAuth2 sample reference away from the stale
third-party `joshiste/spring-boot-admin-samples` repository (last
updated in 2019) and clarify that new example projects belong in
`spring-boot-admin-runtime-playground`.

Refs codecentric#1195
@ozkanpakdil
ozkanpakdil marked this pull request as ready for review October 5, 2026 20:35
@ozkanpakdil
ozkanpakdil requested a review from a team as a code owner October 5, 2026 20:35
@ulischulte ulischulte self-assigned this Oct 16, 2026

@ulischulte ulischulte left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @ozkanpakdil,

Thanks for contributing. I just have some questions, and - after testing some scenarios on my machine - a proposal to an adjusted SecurityFilterChain.

In my local setup I used this additional application properties:

# Redirect URI to register in Google Cloud Console: http://localhost:8080/login/oauth2/code/google
# Set the OAuth consent screen to "Testing" with only your own account as test user,
# because every Google account that passes consent would otherwise be authenticated as admin.

spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: ${GOOGLE_CLIENT_ID}
            client-secret: ${GOOGLE_CLIENT_SECRET}
            scope: openid,profile,email
  boot:
    admin:
      client:
        username: "user"        # embedded client registers itself via HTTP Basic
        password: "password"
        instance:
          metadata:
            user.name: "user"          # server calls its own actuator via HTTP Basic
            user.password: "password"
sample:
  oauth2:
    pr-entry-point: false   # true = the catch-all LoginUrlAuthenticationEntryPoint proposed in PR #5751
    login-page: false   # true = original docs config: oauth2Login().loginPage("/login") + permitAll("/login")
    http-basic: true    # false = no httpBasic()
    csrf-sba: true      # false = Spring Security default CSRF (no /instances ignore, no CustomCsrfFilter)
info.tags.security: oauth2-google

These were my results:

Request A proposed B original C original + basic D no CSRF block E PR snippet
GET / browser Accept 302 → /oauth2/authorization/google 302 → /login 302 → /login 302 → google 302 → google
GET / Accept: text/html 302 → google 302 → /login 302 → /login 302 → google 302 → google
GET / Accept: */* 401 302 → /login 401 401 302 → google
GET / XHR (X-Requested-With, JSON) 401 302 → /login 401 401 302 → google
GET /login content Spring "Please sign in" + Google link SBA local form SBA local form Spring + Google link Spring + Google link
GET /instances Basic 200 302 → /login 200 200 200
POST /instances Basic 201 302 → /login 201 401 201
DELETE /instances/x Basic 404 (reached handler) 302 → /login 404 401 404
POST /instances no credentials 401 302 → /login 401 401 302 → google

Questions:

  1. How was the GET / that returned 401 issued? With a browser Accept header and the documented snippet, I get a
    302 to SBA's local /login. 401 appears only with Accept: */* and httpBasic() present.
  2. The documented snippet had no httpBasic(), so Basic credentials are ignored and clients cannot register. Which
    configuration produced the 401?
  3. What does an XHR call from the UI get with the catch-all entry point after a session expires? In my test it gets a
    302 to the IdP, where redirectOn401 needs a 401. Can you confirm in a browser?
  4. Why is the explicit entry point needed? oauth2Login(Customizer.withDefaults()) with one registration already
    redirects browser requests.
  5. The snippet does not ignore CSRF for /instances. Without it, client registration fails with 401. Can the CSRF
    block be included?
  6. What happens with more than one registration, where the single-registration auto-redirect doesn't apply and the
    hardcoded keycloak id becomes wrong?

Comment on lines +450 to +471
@@ -450,9 +460,15 @@ public SecurityFilterChain filterChain(HttpSecurity http,
.permitAll()
.anyRequest().authenticated()
)
.oauth2Login(oauth2 -> oauth2
.loginPage(adminServer.path("/login"))
)
.oauth2Login(Customizer.withDefaults())
// Keep HTTP-Basic so the Spring Boot Admin Client can still (de-)register itself.
// Clients send the "Authorization" header preemptively, so they never reach the
// entry point below - it only affects requests that carry no credentials at all.
.httpBasic(Customizer.withDefaults())
.exceptionHandling(exceptions -> exceptions
.defaultAuthenticationEntryPointFor(
new LoginUrlAuthenticationEntryPoint("/oauth2/authorization/keycloak"),
AnyRequestMatcher.INSTANCE))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The AnyRequestMatcher entry point breaks non-browser unauthenticated requests, so it affects every unauthenticated non-HTML request, including XHR and Accept: /.

The root cause is loginPage("/login") (SBA's local form) and, in the original snippet, the missing httpBasic() (clients cannot register). Browsers did not get 401. A 401 appears only for Accept: /.

I would also add the CSRF section here. Without the ignore for /instances (POST), /instances/* (DELETE) and /actuator/**, clients cannot register and get 401.

Suggested change
@Bean
public SecurityFilterChain filterChain(HttpSecurity http,
AdminServerProperties adminServer) throws Exception {
http
.authorizeHttpRequests(auth -> auth
.requestMatchers(PathPatternRequestMatcher.withDefaults()
.matcher(adminServer.path("/assets/**")))
.permitAll()
.anyRequest().authenticated()
)
// No custom loginPage: Spring Security redirects browsers to the IdP.
.oauth2Login(Customizer.withDefaults())
// Lets Spring Boot Admin Clients register with Basic credentials.
.httpBasic(Customizer.withDefaults())
.logout(logout -> logout
.logoutUrl(adminServer.path("/logout"))
.logoutSuccessUrl(adminServer.path("/"))
)
.csrf(csrf -> csrf
.csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
.csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler())
.ignoringRequestMatchers(
PathPatternRequestMatcher.withDefaults()
.matcher(POST, adminServer.path("/instances")),
PathPatternRequestMatcher.withDefaults()
.matcher(DELETE, adminServer.path("/instances/*")),
PathPatternRequestMatcher.withDefaults()
.matcher(adminServer.path("/actuator/**"))));
// Also add the CustomCsrfFilter from the CSRF Protection page.
return http.build();
}

Maybe even add a one-line :::warning: do not set loginPage(adminServer.path("/login")), because that is SBA's local form without an IdP link. Add a note that curl without Accept: text/html gets 401 by design, and that an expired UI session lands on Spring's generated login page.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Due to missing feedback, I applied the suggested changes.

Drop the catch-all LoginUrlAuthenticationEntryPoint and the /login permit,
add CSRF exemptions for client registration, and warn against using SBA's
local /login as OAuth2 login page.
With OAuth2 configured, Spring Boot no longer creates a user from
spring.security.user.*, so the snippet now defines its own user
bean for clients that register with Basic auth. It also registers
CustomCsrfFilter.

A failed CSRF check can show as 401 instead of 403 when the error
page also requires login. The docs now mention both codes.

When a context path is set, an expired UI session lands on SBA's
own login form, not the identity provider. The docs now say so.
@ulischulte
ulischulte merged commit 345e0e4 into codecentric:master Nov 20, 2026
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants